<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Updates</title>
<link media="all" rel="stylesheet" type="text/css" href="styles/03e73060321a0a848018724a6c83de7f-theme-base.css" />
<link media="all" rel="stylesheet" type="text/css" href="styles/03e73060321a0a848018724a6c83de7f-theme-medium.css" />

 </head>
 <body class="docs"><div class="navbar navbar-fixed-top">
  <div class="navbar-inner clearfix">
    <ul class="nav" style="width: 100%">
      <li style="float: left;"><a href="mongo.queries.html">« Querying</a></li>
      <li style="float: right;"><a href="mongo.security.html">Security »</a></li>
    </ul>
  </div>
</div>
<div id="breadcrumbs" class="clearfix">
  <ul class="breadcrumbs-container">
    <li><a href="index.html">PHP Manual</a></li>
    <li><a href="mongo.manual.html">Manual</a></li>
    <li>Updates</li>
  </ul>
</div>
<div id="layout">
  <div id="layout-content"><div id="mongo.updates" class="chapter">
 <h1>Updates</h1>


 <p class="para">
  Updates can be one of the most complicated operation available with 
  MongoDB.  They combine a query with an action, modifying documents that match
  the criteria.  They are also extremely powerful, allowing you to change 
  documents quickly and replace them altogether.  They are done in-place (when 
  possible) with little overhead. 
 </p>

 <div class="section">
  <h2 class="title">Modifying vs. replacing documents</h2>

  <p class="para">
   There are two types of updates you can use: modifying updates and replacing
   updates.  Modifying updates contain $-operators and change fields in a 
   document: they might increment counters, push new elements onto an array, 
   or change the type of a field.
  </p>

  <p class="para">
   For example, a modifying update could add a new field to a document.
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #FF8000">/**&nbsp;suppose&nbsp;documents&nbsp;look&nbsp;like:<br />&nbsp;*&nbsp;{"username"&nbsp;:&nbsp;"...",&nbsp;"password"&nbsp;:&nbsp;"...",&nbsp;"email"&nbsp;:&nbsp;"..."}<br />&nbsp;*/<br /></span><span style="color: #0000BB">$coll</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">update</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"username"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"joe"</span><span style="color: #007700">),&nbsp;array(</span><span style="color: #DD0000">'$set'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;array(</span><span style="color: #DD0000">"twitter"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"@joe4153"</span><span style="color: #007700">)));<br /><br /></span><span style="color: #FF8000">/**&nbsp;now&nbsp;the&nbsp;document&nbsp;will&nbsp;look&nbsp;like:<br />&nbsp;*&nbsp;{"username"&nbsp;:&nbsp;"joe",&nbsp;"password"&nbsp;:&nbsp;"...",&nbsp;"email"&nbsp;:&nbsp;"...",&nbsp;"twitter"&nbsp;:&nbsp;"@joe4153"}<br />&nbsp;*/<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </p>

  <p class="para">
   Replacing updates replace the entire matching document with a new document.
   They are generally not as efficient as using $-modifiers, but can be very
   usefully for complex operations or updates that can&#039;t be expressed in terms
   of $-operators.
  </p>

  <p class="para">
   For example, a replacing update can completely change the structure of a
   document.
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #FF8000">/**&nbsp;suppose&nbsp;documents&nbsp;look&nbsp;like:<br />&nbsp;*&nbsp;{"username"&nbsp;:&nbsp;"...",&nbsp;"password"&nbsp;:&nbsp;"...",&nbsp;"email"&nbsp;:&nbsp;"..."}<br />&nbsp;*/<br /></span><span style="color: #0000BB">$coll</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">update</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"username"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"joe"</span><span style="color: #007700">),&nbsp;array(</span><span style="color: #DD0000">"userId"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">12345</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"info"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;array(<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #DD0000">"name"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"joe"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"twitter"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"@joe4153"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"email"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"..."</span><span style="color: #007700">),&nbsp;</span><span style="color: #DD0000">"likes"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;array()));<br /><br /></span><span style="color: #FF8000">/**&nbsp;now&nbsp;the&nbsp;document&nbsp;will&nbsp;look&nbsp;like:<br />&nbsp;*&nbsp;{<br />&nbsp;*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"userId"&nbsp;:&nbsp;12345,&nbsp;<br />&nbsp;*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"info"&nbsp;:&nbsp;{<br />&nbsp;*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"name"&nbsp;:&nbsp;"joe",&nbsp;<br />&nbsp;*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"twitter"&nbsp;:&nbsp;"@joe4153",&nbsp;<br />&nbsp;*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"email"&nbsp;:&nbsp;"..."<br />&nbsp;*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br />&nbsp;*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"likes"&nbsp;:&nbsp;[]<br />&nbsp;*&nbsp;}<br />&nbsp;*/<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </p>

 </div>

 <div class="section">
  <h2 class="title">Updating Nested Objects</h2>

  <p class="para">
   Suppose we wish to change the name of a comment&#039;s author in this document:

   <div class="example-contents">
<div class="javascriptcode"><pre class="javascriptcode">{ 
    &quot;_id&quot; : ObjectId(&quot;4b06c282edb87a281e09dad9&quot;), 
    &quot;content&quot; : &quot;this is a blog post.&quot;,
    &quot;comments&quot; : 
    [
        {
            &quot;author&quot; : &quot;Mike&quot;,
            &quot;comment&quot; : &quot;I think that blah blah blah...&quot;,
        },
        {
            &quot;author&quot; : &quot;John&quot;,
            &quot;comment&quot; : &quot;I disagree.&quot;
        }
    ]
}</pre>
</div>
   </div>


   In order to change an inner field, we use $set (so that all of the other 
   fields are not removed!) with the index of comment to change:

   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br />$blog</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">update</span><span style="color: #007700">(</span><span style="color: #0000BB">$criteria</span><span style="color: #007700">,&nbsp;array(</span><span style="color: #DD0000">'$set'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;array(</span><span style="color: #DD0000">"comments.1"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;array(</span><span style="color: #DD0000">"author"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"Jim"</span><span style="color: #007700">))));<br /><br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </p>
 </div>

 <div class="section">
  <h2 class="title">The Positional Operator</h2>
  <p class="para">
   The positional operator <code class="literal">$</code> is useful for updating objects 
   that are in arrays.  In the example above, for instance, suppose that we did
   not know the index of the comment that we needed to change, merely that we
   needed to change &quot;John&quot; to &quot;Jim&quot;.  We can use <code class="literal">$</code> to do so.
  </p>
  <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br />$blog</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">update</span><span style="color: #007700">(<br />&nbsp;&nbsp;&nbsp;&nbsp;array(</span><span style="color: #DD0000">"comments.author"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"John"</span><span style="color: #007700">),&nbsp;<br />&nbsp;&nbsp;&nbsp;&nbsp;array(</span><span style="color: #DD0000">'$set'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;array(</span><span style="color: #DD0000">'comments.$.author'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"Jim"</span><span style="color: #007700">)));<br /><br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
  </div>

 </div>
</div>
</div></div></body></html>